JohanLe / me-app

 * class ActionContainer

 *

 * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]

 **/

'use strict';

var format = require('util').format;

// Constants

var c = require('./const');

var $$ = require('./utils');

//Actions

var ActionHelp = require('./action/help');

var ActionAppend = require('./action/append');

var ActionAppendConstant = require('./action/append/constant');

var ActionCount = require('./action/count');

var ActionStore = require('./action/store');

var ActionStoreConstant = require('./action/store/constant');

var ActionStoreTrue = require('./action/store/true');

var ActionStoreFalse = require('./action/store/false');

var ActionVersion = require('./action/version');

var ActionSubparsers = require('./action/subparsers');

// Errors

var argumentErrorHelper = require('./argument/error');

/**

 * new ActionContainer(options)

 *

 * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]

 *

 * ##### Options:

 *

 * - `description` -- A description of what the program does

 * - `prefixChars`  -- Characters that prefix optional arguments

 * - `argumentDefault`  -- The default value for all arguments

 * - `conflictHandler` -- The conflict handler to use for duplicate arguments

 **/

var ActionContainer = module.exports = function ActionContainer(options) {

  options = options || {};

  this.description = options.description;

  this.argumentDefault = options.argumentDefault;

  this.prefixChars = options.prefixChars || '';

  this.conflictHandler = options.conflictHandler;

  // set up registries

  this._registries = {};

  // register actions

  this.register('action', null, ActionStore);

  this.register('action', 'store', ActionStore);

  this.register('action', 'storeConst', ActionStoreConstant);

  this.register('action', 'storeTrue', ActionStoreTrue);

  this.register('action', 'storeFalse', ActionStoreFalse);

  this.register('action', 'append', ActionAppend);

  this.register('action', 'appendConst', ActionAppendConstant);

  this.register('action', 'count', ActionCount);

  this.register('action', 'help', ActionHelp);

  this.register('action', 'version', ActionVersion);

  this.register('action', 'parsers', ActionSubparsers);

  // raise an exception if the conflict handler is invalid

  this._getHandler();

  // action storage

  this._actions = [];

  this._optionStringActions = {};

  // groups

  this._actionGroups = [];

  this._mutuallyExclusiveGroups = [];

  // defaults storage

  this._defaults = {};

  // determines whether an "option" looks like a negative number

  // -1, -1.5 -5e+4

  this._regexpNegativeNumber = new RegExp('^[-]?[0-9]*\\.?[0-9]+([eE][-+]?[0-9]+)?$');

  // whether or not there are any optionals that look like negative

  // numbers -- uses a list so it can be shared and edited

  this._hasNegativeNumberOptionals = [];

};

// Groups must be required, then ActionContainer already defined

var ArgumentGroup = require('./argument/group');

var MutuallyExclusiveGroup = require('./argument/exclusive');

//

// Registration methods

//

/**

 * ActionContainer#register(registryName, value, object) -> Void

 * - registryName (String) : object type action|type

 * - value (string) : keyword

 * - object (Object|Function) : handler

 *

 *  Register handlers

 **/

ActionContainer.prototype.register = function (registryName, value, object) {

  this._registries[registryName] = this._registries[registryName] || {};

  this._registries[registryName][value] = object;

};

ActionContainer.prototype._registryGet = function (registryName, value, defaultValue) {

  if (arguments.length < 3) {

    defaultValue = null;

  }

  return this._registries[registryName][value] || defaultValue;

};

//

// Namespace default accessor methods

//

/**

 * ActionContainer#setDefaults(options) -> Void

 * - options (object):hash of options see [[Action.new]]

 *

 * Set defaults

 **/

ActionContainer.prototype.setDefaults = function (options) {

  options = options || {};

  for (var property in options) {

    if ($$.has(options, property)) {

      this._defaults[property] = options[property];

    }

  }

  // if these defaults match any existing arguments, replace the previous

  // default on the object with the new one

  this._actions.forEach(function (action) {

    if ($$.has(options, action.dest)) {

      action.defaultValue = options[action.dest];

    }

  });

};

/**

 * ActionContainer#getDefault(dest) -> Mixed

 * - dest (string): action destination

 *

 * Return action default value

 **/

ActionContainer.prototype.getDefault = function (dest) {

  var result = $$.has(this._defaults, dest) ? this._defaults[dest] : null;

  this._actions.forEach(function (action) {

    if (action.dest === dest && $$.has(action, 'defaultValue')) {

      result = action.defaultValue;

    }

  });

  return result;

};

//

// Adding argument actions

//

/**

 * ActionContainer#addArgument(args, options) -> Object

 * - args (String|Array): argument key, or array of argument keys

 * - options (Object): action objects see [[Action.new]]

 *

 * #### Examples

 * - addArgument([ '-f', '--foo' ], { action: 'store', defaultValue: 1, ... })

 * - addArgument([ 'bar' ], { action: 'store', nargs: 1, ... })

 * - addArgument('--baz', { action: 'store', nargs: 1, ... })

 **/

ActionContainer.prototype.addArgument = function (args, options) {

  args = args;

  options = options || {};

  if (typeof args === 'string') {

    args = [ args ];

  }

  if (!Array.isArray(args)) {

    throw new TypeError('addArgument first argument should be a string or an array');

  }

  if (typeof options !== 'object' || Array.isArray(options)) {

    throw new TypeError('addArgument second argument should be a hash');

  }

  // if no positional args are supplied or only one is supplied and

  // it doesn't look like an option string, parse a positional argument

  if (!args || args.length === 1 && this.prefixChars.indexOf(args[0][0]) < 0) {

    if (args && !!options.dest) {

      throw new Error('dest supplied twice for positional argument');

    }

    options = this._getPositional(args, options);

    // otherwise, we're adding an optional argument

  } else {

    options = this._getOptional(args, options);

  }

  // if no default was supplied, use the parser-level default

  if (typeof options.defaultValue === 'undefined') {

    var dest = options.dest;

    if ($$.has(this._defaults, dest)) {

      options.defaultValue = this._defaults[dest];

    } else if (typeof this.argumentDefault !== 'undefined') {

      options.defaultValue = this.argumentDefault;

    }

  }

  // create the action object, and add it to the parser

  var ActionClass = this._popActionClass(options);

  if (typeof ActionClass !== 'function') {

    throw new Error(format('Unknown action "%s".', ActionClass));

  }

  var action = new ActionClass(options);

  // throw an error if the action type is not callable

  var typeFunction = this._registryGet('type', action.type, action.type);

  if (typeof typeFunction !== 'function') {

    throw new Error(format('"%s" is not callable', typeFunction));

  }

  return this._addAction(action);

};

/**

 * ActionContainer#addArgumentGroup(options) -> ArgumentGroup

 * - options (Object): hash of options see [[ArgumentGroup.new]]

 *

 * Create new arguments groups

 **/

ActionContainer.prototype.addArgumentGroup = function (options) {

  var group = new ArgumentGroup(this, options);

  this._actionGroups.push(group);

  return group;

};

/**

 * ActionContainer#addMutuallyExclusiveGroup(options) -> ArgumentGroup

 * - options (Object): {required: false}

 *

 * Create new mutual exclusive groups

 **/

ActionContainer.prototype.addMutuallyExclusiveGroup = function (options) {

  var group = new MutuallyExclusiveGroup(this, options);

  this._mutuallyExclusiveGroups.push(group);

  return group;

};

ActionContainer.prototype._addAction = function (action) {

  var self = this;

  // resolve any conflicts

  this._checkConflict(action);

  // add to actions list

  this._actions.push(action);

  action.container = this;

  // index the action by any option strings it has

  action.optionStrings.forEach(function (optionString) {

    self._optionStringActions[optionString] = action;

  });

  // set the flag if any option strings look like negative numbers

  action.optionStrings.forEach(function (optionString) {

    if (optionString.match(self._regexpNegativeNumber)) {

      if (!self._hasNegativeNumberOptionals.some(Boolean)) {

        self._hasNegativeNumberOptionals.push(true);

      }

    }

  });

  // return the created action

  return action;

};

ActionContainer.prototype._removeAction = function (action) {

  var actionIndex = this._actions.indexOf(action);

  if (actionIndex >= 0) {

    this._actions.splice(actionIndex, 1);

  }

};

ActionContainer.prototype._addContainerActions = function (container) {

  // collect groups by titles

  var titleGroupMap = {};

  this._actionGroups.forEach(function (group) {

    if (titleGroupMap[group.title]) {

      throw new Error(format('Cannot merge actions - two groups are named "%s".', group.title));

    }

    titleGroupMap[group.title] = group;

  });

  // map each action to its group

  var groupMap = {};

    // if a group with the title exists, use that, otherwise

    // create a new group matching the container's group

    if (!titleGroupMap[group.title]) {

      titleGroupMap[group.title] = this.addArgumentGroup({

        title: group.title,

        description: group.description

      });

    }

    // map the actions to their new group

    group._groupActions.forEach(function (action) {

      groupMap[actionHash(action)] = titleGroupMap[group.title];

    });

  }, this);

  // add container's mutually exclusive groups

  // NOTE: if add_mutually_exclusive_group ever gains title= and

  // description= then this code will need to be expanded as above

  var mutexGroup;

  container._mutuallyExclusiveGroups.forEach(function (group) {

    mutexGroup = this.addMutuallyExclusiveGroup({

      required: group.required

    });

    // map the actions to their new mutex group

    group._groupActions.forEach(function (action) {

      groupMap[actionHash(action)] = mutexGroup;

    });

  }, this);  // forEach takes a 'this' argument

  // add all actions to this container or their group

  container._actions.forEach(function (action) {

    var key = actionHash(action);

    if (groupMap[key]) {

      groupMap[key]._addAction(action);

    } else {

      this._addAction(action);

    }

  });

};

ActionContainer.prototype._getPositional = function (dest, options) {

  if (Array.isArray(dest)) {

    dest = dest[0];

  }

  // make sure required is not specified

  if (options.required) {

    throw new Error('"required" is an invalid argument for positionals.');

  }

  // mark positional arguments as required if at least one is

  // always required

  if (options.nargs !== c.OPTIONAL && options.nargs !== c.ZERO_OR_MORE) {

    options.required = true;

  }

  if (options.nargs === c.ZERO_OR_MORE && typeof options.defaultValue === 'undefined') {

    options.required = true;

  }

  // return the keyword arguments with no option strings

  options.dest = dest;

  options.optionStrings = [];

  return options;

};

ActionContainer.prototype._getOptional = function (args, options) {

  var prefixChars = this.prefixChars;

  var optionStrings = [];

  var optionStringsLong = [];

  // determine short and long option strings

  args.forEach(function (optionString) {

    // error on strings that don't start with an appropriate prefix

    if (prefixChars.indexOf(optionString[0]) < 0) {

      throw new Error(format('Invalid option string "%s": must start with a "%s".',

        optionString,

        prefixChars

      ));

    }

    // strings starting with two prefix characters are long options

    optionStrings.push(optionString);

    if (optionString.length > 1 && prefixChars.indexOf(optionString[1]) >= 0) {

      optionStringsLong.push(optionString);

    }

  });

  // infer dest, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'

  var dest = options.dest || null;

  delete options.dest;

  if (!dest) {

    var optionStringDest = optionStringsLong.length ? optionStringsLong[0] : optionStrings[0];

    dest = $$.trimChars(optionStringDest, this.prefixChars);

    if (dest.length === 0) {

      throw new Error(

        format('dest= is required for options like "%s"', optionStrings.join(', '))

      );

    }

    dest = dest.replace(/-/g, '_');

  }

  // return the updated keyword arguments

  options.dest = dest;

  options.optionStrings = optionStrings;

  return options;

};

ActionContainer.prototype._popActionClass = function (options, defaultValue) {

  defaultValue = defaultValue || null;

  var action = (options.action || defaultValue);

  delete options.action;

  var actionClass = this._registryGet('action', action, action);

  return actionClass;

};

ActionContainer.prototype._getHandler = function () {

  var handlerString = this.conflictHandler;

  var handlerFuncName = '_handleConflict' + $$.capitalize(handlerString);

  var func = this[handlerFuncName];

  if (typeof func === 'undefined') {

    var msg = 'invalid conflict resolution value: ' + handlerString;

    throw new Error(msg);

  } else {

    return func;

  }

};

ActionContainer.prototype._checkConflict = function (action) {

  var optionStringActions = this._optionStringActions;

  var conflictOptionals = [];

  // find all options that conflict with this option

  // collect pairs, the string, and an existing action that it conflicts with

  action.optionStrings.forEach(function (optionString) {

    var conflOptional = optionStringActions[optionString];

    if (typeof conflOptional !== 'undefined') {

      conflictOptionals.push([ optionString, conflOptional ]);

    }

  });

  if (conflictOptionals.length > 0) {

    var conflictHandler = this._getHandler();

    conflictHandler.call(this, action, conflictOptionals);

  }

};

ActionContainer.prototype._handleConflictError = function (action, conflOptionals) {

  var conflicts = conflOptionals.map(function (pair) { return pair[0]; });

  conflicts = conflicts.join(', ');

  throw argumentErrorHelper(

    action,

    format('Conflicting option string(s): %s', conflicts)

  );

};

ActionContainer.prototype._handleConflictResolve = function (action, conflOptionals) {

  // remove all conflicting options

  var self = this;

  conflOptionals.forEach(function (pair) {

    var optionString = pair[0];

    var conflictingAction = pair[1];

    // remove the conflicting option string

    var i = conflictingAction.optionStrings.indexOf(optionString);

    if (i >= 0) {

      conflictingAction.optionStrings.splice(i, 1);

    }

    delete self._optionStringActions[optionString];

    // if the option now has no option string, remove it from the

    // container holding it

    if (conflictingAction.optionStrings.length === 0) {

      conflictingAction.container._removeAction(conflictingAction);

    }

  });

};